## 
 # ###################################################################
 #  Vince's Additions - an extension package for Alpha
 # 
 #  FILE: "Documentprojects Help"
 #                                    created: 1/8/97 {2:22:17 pm} 
 #                                last update: 11/28/2001 {10:44:46 AM} 
 #  Author: Vince Darley
 #  E-mail: <vince@santafe.edu>
 #    mail: 317 Paseo de Peralta
 #          Santa Fe, NM 87501, USA
 #     www: <http://www.santafe.edu/~vince/>

 # Copyright (c) 1997-2000  Vince Darley
 # 
 # ###################################################################
 ##

	  	  Personalisation

In order to use many of these additions, you need to enter various pieces 
of information which describe yourself, the projects you work on, and 
document templates which you use.  Some of these are accessed from the 
Config->Packages menu, under 'User Details', others are handled via the 'New 
Document Type' and 'New Project' menu items (hold down option or ctrl to 
edit or delete document types and projects from this menu).

The purpose of 'Projects' is to allow you to have separate templates for 
different things on which you work, and to have different Alpha modes bound 
to different projects by default.

The purpose of Document templates is simply to save you the labour of 
typing in the same sort of basic information for every file you create, and 
to give your files a standard look.  Document headers can also contain 
modification and creating dates, version numbering, all of which may be 
updated very easily.

You can modify the following preferences using the 
'Config->Packages->Document Project Prefs' menu item:

	 overrideNew --- over-ride new 
	 docTemplatesModeSpecific --- new document templates mode specific 
	  (useful if you have lots of templates) 
	 newDocNamePrompt --- prompt for name of new document? 
	 autoUpdateHeader --- Do we auto-update the time-stamp in the header of 
	  a file?
	 untitledDocsAreEmpty --- untitled documents are empty.
	 updateFromInternetConfig --- Do we update user items from internet config? 
	 minItemsInTitlePopup--- number of items in option-title-bar popup before 
	  we add glob'ed directory

Also from the 'File Utils' and electric menus one can access a variety of 
new functions and an extra hierarchical sub-menu, so that you can easily 
add personalised code-tidbits.  Here are some of the features:

	 shift-F2 to update the version number/info of a file header.
	 function and class templates.
	 automatic generation of a pair of (for example) .h/.cc files for a new 
	  class.
	 file-header time-stamp and version details updating
	 comment block generation for procedures

The electric menu contains a 'Templates' sub-menu, which contains global 
templates stored in the variable 'univ::MenuTemplates', and mode-specific
templates stored in variables ${mode}Templates.  The format of these 
variables is a list of names, which correspond to procedures when prepended 
with 'file::'.  You can add new items by using the menu item.

The file utils menu also contains a 'More Utils' sub-menu to allow easy 
addition of your own procedures.  Place procedures for that menu in a 
mode-preferences file for the mode to which they apply.

	  	  Document templates

For each of your different projects and modes you'll probably want a 
standard document template, with a given header, perhaps some code/text 
already filled in,  You can use the Config->Packages menu to create, edit 
and remove document templates.  They can be arbitrarily complex.

	  	  File headers

The file "docProjEngine.tcl" will create new header and source files 
for C, C++ and Tcl code automatically.  As well as creating descriptive 
headers, it can insert actual template code (for a class definition, say).  

The easiest way to see what these functions do is to switch to C++ mode, 
and select 'New Class' from the 'File Utils' menu.  Enter any name when 
prompted in the status bar, and you'll see what these procedures produce.  

	  	  Function Comments

	F1 ---  plain - insert comment block
			opt   - insert small comment block
			cmd   - insert large comment block
			shift - update function comment block version number

Imagine you have the following function (in Tcl for this example):

	proc main {} {
		# just for show
		puts stdout "Hello World"
		exit
	}

and you wish to write a comment block above it, explaining what it does, 
what it returns, what side-effects it may have, and to note down that you 
are the author.  Just double click on the procedure name 'main' to select 
it, and press F1 (with a modifier if desired) and you have a great 
template, in one of three styles (this is for 'cmd-F1'):

	## 
	 # -------------------------------------------------------------------------
	 #   
	 # "main" --
	 #  
	 #  
	 #  		
	 # Results:
	 #  
	 #  
	 # Side effects:
	 #  
	 #  
	 # --Version--Author------------------Changes-------------------------------  
	 #    1.0     <vince@santafe.edu> original
	 # -------------------------------------------------------------------------
	 ##
	proc main {} {
		# just for show
		puts stdout "Hello World"
		exit
	}

Instructions are in the status window below --- you hit Tab to 
move from one bullet mark to the next, hitting return automatically
fills in the left edge of the comment block and indents appropriately!
You'll end up with something like this:

	## 
	 # -------------------------------------------------------------------------
	 #	 
	 #	"main" --
	 #	
	 #	 The main procedure
	 #	 of	my program
	 #		   
	 #	Results:
	 #	 none
	 #	
	 #	Side effects:
	 #	 In	this case just trivial side-effects
	 #	 
	 # --Version--Author------------------Changes-------------------------------  
	 #	  1.0	  <vince@santafe.edu> original
	 # -------------------------------------------------------------------------
	 ##
	proc main {} {
		# just for show
		puts stdout "Hello World"
		exit
	}

Of course the same thing works for C, C++ code etc (and probably other 
modes too; I just haven't tried).  Now if you modify the function, and wish 
to update the version numbering, just put the cursor in the vicinity and 
type shift-F1: the comment is found, an extra version and author detail is 
inserted and you're ready to type your changes!

If the above block is too big, try other modifiers for smaller ones.

================================================================================

	  	  Auto Update

If you want file headers to update the last modified date automatically on 
saving, then make sure you've selected 'auto update header' in the 
universal preferences dialog.

================================================================================
